Games of Daze

home *** CD-ROM | disk | FTP | other *** search

/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / libs / psy_kit / pdfm.doc < prev next >

Wrap

Text File | 1993-10-29 | 14.5 KB | 338 lines

╔══════════════════════════════════════════════════════════════════════════╗ ║ P S Y C H O S E D A T A F I L E M A K E R ║ ║ & ║ ║ P S Y C H O S E D A T A F I L E I N T E R F A C E K I T ║ ║ ║ ║ for Assembly language programming ║ ╟──────────────────────────────────────────────────────────────────────────╢ ║ ║ ║ This is the documentation file for the Psychose Datafile Maker ║ ║ and for the Psychose Datafile Interface Kit ║ ║ ║ ║ -=≡≡≡ P D F M & P D F I K ≡≡≡=- ║ ║ ║ ╟──────────────────────────────────────────────────────────────────────────╢ ║ (C)opyright 1993 by NAPALM from PSYCHOSE, Inc. ║ ╚══════════════════════════════════════════════════════════════════════════╝ = ] ------ Table of contents ------ [ = 1. [Introduction] ........... Hey...ya! What is the PDFM ? 2. [License] ................ Yep yep ! Don't forget it dude... 3. [A matter of food] ....... How to feed this 'byte-eater' utility. 4. [Related stuff: PDFIK] ... Whoa! Cool! But what now ? 5. [PDFIK functions] ........ At last! Calling PDFIK from assembly. 5.1 What you need to include in your source code 5.2 Calling conventions 6. [To contact me] .......... BBS, Minitel and all that. 7. [Good bye user] .......... Latest information. = ] ------------------------------- [ = 1. [Introduction] The PSYCHOSE Datafile Maker (PDFM) is a small utility designed to help you create special files, called datafiles, where you put all the data (such as images, musics or texts ) you need for a demo. The original data is compressed using a standard Lempel-Ziv algorithm which can achieve good compression ratios, saving space (and also disks when it's time to release your demo...). Even if this is supposed to be a standard utility, you'll need at least a 386 to run this program, because I used several 386 instructions during coding. (I know what ya're goin' to tell me but forget it !!!) 2. [License] You are free to use, distribute or copy PDFM and PDFIK, but only under the following conditions: ■ The program using PDFM and PDFIK is not a commercial one (Shareware is considered as commercial software) ■ You must mention in your program and/or in its documentation you used PDFM and/or PDFIK, that is give us credits for the work we've done! ■ PDFM and PDFIK are not modified in any way, and stay in their original form. If you decide to copy PDFM and PDFIK to a friend (and you are encouraged to do so...), please copy the full package with its documentation, include and executable files. 3. [A matter of food] You'll have to provide the PDFM with a Listfile, that is, a file containing the name of the Datafile (were the packed data is stored) and the names of the files you want to include in that Datafile. The Listfile is an ASCII file organized as follows: ┌────────────┐ │DATANAME.EXT│ <───■ Datafile name (MUST be the first one...) │FILE1.EXT │ <───■ File name n°1 │FILE2.EXT │ <───■ File name n°2 │ . │ │ . │ │ . │ │FILEn.EXT │ <───■ The last file name │∞ │ <───■ [ALT 236] character for 'end of input' └────────────┘ note: there must be only one name per line. 4. [Related stuff: PDFIK] The Datafile is nice, isn't it dear ? wha ah ah ah ah! ...hum... So now you got a Datafile ready but a simple question flashed through your mind...: Hey Dude! How do I use the Datafile from my source code ? Well...er... PSYCHOSE is here again to help you! I coded a special interface called PSYCHOSE Datafile Interface Kit (PDFIK) which implements cool functions for lazy loading of a specified file from the Datafile (where it's stored...) into a memory buffer. This lazy interface offers full support of 32BMM (another cool OBJ from ...? Guess who...? PSYCHOSE evidently...) See the next section for more precise details. 5. [PDFIK functions] Remember you must have at least a 386 to run any of these routines! and when using .386P or .486 directives don't forget to specify the USE16 directive in segment(s) declaration(s). (besides the functions will not test any of these for you...) 5.1 What you need to include in your source code just insert the following line in your code: include PDFIK.INC The PDFIK.INC file contains the necessary declarations and data stuctures to communicate with the PDFIK. Here is a copy of its contents: EXTRN PDFIK_ASM : FAR ; Main routine (external) PARAM_STRUC STRUC ; Structure to pass & receive parameters Function db ? ; Function number DtaSeg dw ? ; Segment of related datas DtaOfsPdf dw ? ; Offset in DtaSeg of datafile name (ASCIIZ) DtaOfsFil dw ? ; Offset in DtaSeg of file name (ASCIIZ) OfsInPdf dd ? ; Offset from beginning of Datafile OfsInFil dd ? ; Offset from beginning of File NumBytes dd ? ; Number of bytes to decompress BufSeg dw ? ; Segment of buffer where to unpack the data BufOfs dw ? ; Offset in BufSeg FlatMode db ? ; 0=No 32BMM, 1=32BMM use/compatible. MemMode db ? ; Memory mode of output buffer (see 32BMM ref.) MemHandle dw ? ; Handle of output buffer (32BMM support) LinearOfs dd ? ; 32bit linear offset of output buffer (32BMM) NormSize dd ? ; Size of the normal file (unpacked) PackSize dd ? ; Size in the datafile (packed) ErrorCode db ? ; Return code from PDFIK PARAM_STRUC ENDS ; End of structure I think all the fields are self-explanatory (Ok, Ok I'm the coder so it's normal no?) except perhaps the OfsInPdf field. This field is used when the Datafile is integrated in the EXE, that is when you (and everyone for sure!) want the Datafile to be part of the EXE file, so that you release only one (Big!) EXE. This 32 bit number represents the size of the EXE just after compile process is complete. To include the Datafile in the EXE just type: COPY /B PROG.EXE+DATAFILE.EXT NEWPROG.EXE and remember to use the 'NEWPROG.EXE' filename for the DtaOfsPdf field (that is, as the Datafile name!). coder's advice: You don't need to set up all the fields each time you call one function (this will lead to a real nightmare! huhu...). In fact fill the "general purpose" fields in some initilization routine at the beginning of yar program and then you just have to fill 3 or 4 fields at each call (unless ya wanna change some settings!). 5.2 Calling conventions Please refer to the 32BMM reference for detailed explanations about the fields referencing use of 32BMM. We assume here that the 'x' label refers to a PARAM_STRUC type structure declared and allocated in your Data Segment as follows: x PARAM_STRUC <,,,,,,,,,> At this moment only three functions are available. The first one is called [GetInfo] and is used to obtain information (i.e: the size of the original file, and its size in the Datafile) about a specified file stored in the Datafile. The second function is [Extract] and... huhu... is used to extract a file from the Datafile to a memory buffer. The third one is [Extract2] and provides the laziest loading of a file because it takes less parameters and allocates directly the memory (which has to be de-allocated by user..). You can call the three routines like this: mov x.Function,(Function number) ... <Fill all necessary fields> ... mov ES,(Segment of x) mov BX,(Offset of x) call PDFIK_ASM <Check the return code> [GetInfo routine] ■ before call: x.Function = 0 x.DtaSeg = Address of DATA segment (for following datas) x.DtaOfsPdf = Offset of ASCIIZ string for Datafile name (string example: Datafile db 'DATA1.DTA',0 ) x.DtaOfsFil = Offset of ASCIIZ string for file name (string example: File db 'TEXT.DOC',0 ) x.OfsInPdf = Offset for beginning of Datafile in EXE (i.e: size of the EXE file) This value is 0 when Datafile is not integrated in a EXE. ES:BX = pointer to the x structure (PARAM_STRUC type) ■ after call: x.NormSize = Size of original file (for memory allocation) x.PackSize = Size of packed file x.ErrorCode = return code from PDFIK 0 = OK, no problemo! 1 = Datafile not found (wrong name, ...) 2 = Invalid format (not a PSYCHOSE Datafile) 3 = File not found in Datafile (wrong name, ...) 4 = Memory allocation error (used by [Extract2]) ES:BX = pointer to the x structure (PARAM_STRUC type) [Extract routine] ■ before call: x.Function = 1 x.DtaSeg = Address of DATA segment (for following datas) x.DtaOfsPdf = Offset of ASCIIZ string for Datafile name (string example: Datafile db 'DATA1.DTA',0 ) x.DtaOfsFil = Offset of ASCIIZ string for file name (string example: File db 'TEXT.DOC',0 ) x.OfsInPdf = Offset for beginning of Datafile in EXE (i.e: size of the EXE file) This value is 0 when Datafile is not integrated in a EXE. x.BufSeg = Segment of buffer where we unpack (allocated by user) x.BufOfs = Offset in BufSeg ES:BX = pointer to the x structure (PARAM_STRUC type) ■ after call: x.ErrorCode = return code (see GetInfo) ES:BX = pointer to the x structure (PARAM_STRUC type) [Extract2 routine - 32BMM compatible] ■ before call: x.Function = 2 x.DtaSeg = Address of DATA segment (for following datas) x.DtaOfsPdf = Offset of ASCIIZ string for Datafile name (string example: Datafile db 'DATA1.DTA',0 ) x.DtaOfsFil = Offset of ASCIIZ string for file name (string example: File db 'TEXT.DOC',0 ) x.OfsInPdf = Offset for beginning of Datafile in EXE (i.e: size of the EXE file) This value is 0 when Datafile is not integrated in a EXE. x.OfsInFil = Offset from which we begin to unpack (i.e: how many bytes we jump in the original file before unpacking) x.NumBytes = How many bytes we unpack (0 means unpack ALL) x.FlatMode = 0 means standard DOS memory allocation 1 means 32BMM Flat Real Mode memory allocation ES:BX = pointer to the x structure (PARAM_STRUC type) ■ after call: x.ErrorCode = return code (see GetInfo) if x.FlatMode was 1 x.LinearOfs = 32bits linear address of output buffer x.MemMode = Memory mode of output buffer (Save it!) x.MemHandle = Handle of output buffer (Save it!) else x.BufSeg = Segment of output buffer ES:BX = pointer to the x structure (PARAM_STRUC type) Note: this is very easy to convert a standard segment to a 32bits linear address compatible with 32BMM. Just multiply the segment value by 16 and you'll get it ! For example if AX contains the segment value, ESI will contain the 32bits linear address after the follwing lines: movzx esi,ax shl esi,4 ... 6. [To contact me] (Hey! no illegal stuff ok?) If you're French use your Minitel: 3615 RTEL BAL NAPALM (alors les p'tits gars ça flotte ? Hehe...) For a personal contact write to: ┌───────────────────────┐ │ Rémy Chibois (NAPALM) │ └───────────┬───────────┘ ┌──────────────────────────┐ │ ┌───────────────────┐ │ 1 ter Av. de l'étang │<───┴───>│ 43 rue de Chabrol │ │ 78320 Le Mesnil St Denis │ │ 75010 Paris │ │ FRANCE │ │ FRANCE │ └──────────────────────────┘ └───────────────────┘ 7. [Good bye user] I intend to improve the compression algorithm, of course, and new functions will also be added to ensure a more flexible use. (is that possible ? Haha..) Well now you're on your own, and I wish this utility will be usefull to you. Please don't make lame with this utility and give us the credits we deserve if you decide to use this program. You can send me your demos if you're pleased with PDFM & PDFIK !! Have a pleasant coding.